SPACE 1/SPACE - Library 1 - Volume 1.iso/program/569/rsctools/rsh.man

Text File | 1992-06-01 | 17KB | 362 lines

RSH                        ST Programmer's Manual                       RSH


NAME

      rsh - generates C source code from GEM resource files

SYNOPSIS

      rsh [-bflnqstvV] [-ac [skeleton-file]] infile [outfile]

DESCRIPTION

      Rsh is a utility designed to facilitate imbedding of resource files
      within GEM applications.  The basic function of rsh is generation
      of "RSH" output files based on resource file data, where an RSH
      file is a C source file following the conventions defined by the
      DRI/Atari resource construction program (RCS).  Rsh goes beyond RCS
      in speed, convenience of use, compiler-dependent keyword support, and
      automation of the imbedding process.  In particular, rsh can be used
      in a makefile, and as long as an appropriate rule is defined for
      making a .c file from a .rsc file, one can just include the .o filename
      with the list of objects comprising the program, and make will call
      rsh transparently (and if it's a good make, it will delete the
      intermediate .c file, leaving just the .rsc and the compiled .o file).
      To complete the automation process, rsh is capable of merging its
      output with a "skeleton file," which contains the necessary replacements
      for `rsrc_load' and other GEM functions; when this option is used,
      rsh generates a stand-alone source file that includes everything
      needed to imbed a resource within an application.


      Generating RSH Files
      --------------------

      In its simplest form, the syntax for the rsh command is:

         rsh resource-file

      An extension isn't required for the resource file; if none is present,
      rsh appends ".RSC" to the filename (if the file in fact has no extension,
      indicate this by ending the filename with a period).  The above command
      creates a file with the same basename as the resource file but with
      the extension "RSH"; the RSH file is created in the current directory.
      If the file should be placed elsewhere or given a different basename,
      the "outfile" must be specified.  For example,

         rsh c:\test f:\src\out

      results in out.rsh being placed in the f:\src directory.  Notice that
      the RSH extension was appended in this case; if instead we specified the
      outfile as "out.", no extension would be appended.  If we had specified
      the outfile as "out.c", then this name would be used as is.


      Compiler and Language Keyword Support
      -------------------------------------

      Since it's always a good programming practice to hide as much detail
      as possible, rsh supports the C `static' keyword through the `-s'
      option.  When `-s' is used, `rs_object', `rs_tedinfo', etc. are all
      made static (note that this doesn't make any sense unless using the
      skeleton file merging feature, described later).

      The Lattice C 5 compiler supports the modifiers `__near' and `__far',
      which control the section where data is placed.  In particular, a
      Lattice C 5 program has 64 K of near (base-relative) data, which can
      be accessed more efficiently than far (absolute) data.  Since resource
      file data is almost always accessed via pointers, for which this
      distinction is meaningless, it's desirable to make the resource data
      far, so that it doesn't consume precious near data space.  Use the `-f'
      option to make all resource data far and `-n' to make it near.  These
      two options are mutually exclusive, and the default is to use neither.

      Note: although Lattice C 5 supports __far data, the semantics of this
      modifier appear to be only partially implemented.  For example, the
      following statement:

         char * __far rs_strings[] = {"a", "b",};

      makes the array `rs_strings' far, but _not_ the data.  This is expected.
      However, ideally, one could use __far a second time to make the data
      itself far, as in

         __far char * __far rs_strings...

      but this doesn't seem to work.  According to the compiler output, all
      the string data ends up in the merged or near data section, while the
      array is placed in the far data segment.  If one uses the `-cs' compiler
      option, which merges identical string constants, the array data is moved
      out of the near segment and into the code segment, which effectively
      makes it far (however, it would be better if the data was placed in
      the data segment, where it properly belongs).


      Compatibility Considerations
      ----------------------------

      Unfortunately, not all compilers agree on types used to define GEM data
      structures, nor do all resource construction programs create identical
      resource files.  Rsh provides the following options which can account for
      for these inconsistencies:

         Kuma/Mark Williams editor - This resource construction program treats
            TEDINFOs differently from all other editors known to the author.
            The Kuma editor pads the `te_ptext' field with zeros, so that it
            will be at least as long as the `te_pvalid' field.  This is
            presumably meant to be a safeguard, so that one needn't replace
            the `te_ptext' pointer at run-time with the address of an array
            large enough to hold the edited text (a very common practice).
            Since rsh has no way of knowing what program created the resource,
            one must use the `-t' option to force the Kuma-style treatment of
            TEDINFOs.  But as long as one isn't depending on this undocumented
            feature of the editor, smaller programs can be obtained by not
            using this option.

         Escaping characters - Of course, the backslash and double quote
            must be escaped with a backslash to be used literally in a
            quoted string.  Since the `rs_strings' array is initialized with
            quoted strings, this can present a problem.  Use the `-b' option
            to force escaping of backslashes and use the `-q' option to
            force escaping of quotes.  Since escaping may be controlled
            through these options, one needn't modify any resource files
            in which characters are already escaped.

         The type of `ob_spec' - depending on one's views, `ob_spec' might
            have the type "unsigned long" or "void *".  By default rsh assumes
            "void *", in order to conform with the Lattice C 5 aes.h OBJECT
            typedef.  Since compilers vary in their treatment of type
            mismatches in initialized data, rsh explicitly casts `ob_spec',
            as well as all other potential type conflicts.  Thus, the rsh
            default is to cast `ob_spec' as in "(void *) 1L".  However, some
            may feel that the "unsigned long" type is more appropriate, even
            to the point of modifying the aes.h file.  Use the `-l' option to
            suppress the (void *) casting.


      Skeleton Files
      --------------

      As alluded to earlier, generation of an RSH file still leaves the
      application writer with quite a bit of work in order to imbed the
      resource file.  He absolutely must provide replacements for `rsrc_load'
      and other members of the rsrc family; one approach is to maintain a
      rsrc.c file containing these functions, with a #include "some-rsh-file"
      line.  The file would typically be copied to a project directory and
      the #include made specific.  Rsh provides a better way through its
      "skeleton file" feature.

      A skeleton file is a source file containing whatever preprocessor
      statements and functions that are necessary to complete the imbedding
      process.  When the `-c' option is given, rsh copies the skeleton file
      to its outfile, merging its RSH output at the position of the "%%" token
      within the skeleton file.  The double-percent token must be in the first
      column of a line, and it may not be followed by any character (other
      than a line-terminator), if it is to recognized.

      Rsh locates skeleton files based on how they are specified on the
      command line.  If the filename is given by itself (with no path
      information), rsh searches for it in the directories listed in the
      "LIB" environment variable; the feature will not work unless LIB is
      defined.  On the other hand, if you specify a more or less fully
      qualified path for the skeleton file, rsh won't consult LIB; rather,
      it will look for the file only in the place you indicated.  The
      default skeleton file is "c_rsh.skl" located along the LIB path.

         Example 1: rsh -c test.rsc

            This command causes the c_rsh.skl skeleton file to be merged with
            rsh's RSH output.  The outfile is implicitly named test.rsh.

         Example 2: rsh -cother.skl test.rsc test.c

            This command causes the other.skl skeleton file to be merged with
            rsh's RSH output, and the resulting file is named test.c.  If a
            filename is given as an argument to the `-c' option, it must
            immediately follow it, as above, because `-c' optionally takes
            an argument.  Other.skl must lie along the LIB path for this to
            work.

         Example 3: rsh -c.\other.skl test.rsc test.c

            Similar to example 2, except rsh looks for other.skl only in the
            current directory.

         Example 4: rsh -cd:\skel\other.skl test.rsc test.c

            Similar to example 3, except rsh looks for other.skl only in the
            d:\skel directory.


      Putting it all together - rsh, skeleton files, and make
      -------------------------------------------------------

      For illustration purposes, let's consider the following makefile,
      designed for the GNU make and Lattice C 5:

         %.c : %.rsc
            rsh -fls -c $< $@

         OBJS=\
         main.o\
         test.o

         CFLAGS=-rr -v -w -cfuis -d1

         testrsc.prg: $(OBJS)
            clink.ttp   FROM  e:\lc\lib\csr.o\
                              $(OBJS)\
                        TO    $@\
                        LIB   lcgsr.lib\
                              lcsr.lib\
                        BATCH XADDSYM

      This makefile defines a program, `testrsc.prg', made from the objects
      `main.o' and `test.o'.  While main.o has a corresponding .c file, test.o
      does not.  Rather, test.o is made directly from test.rsc.  This is
      possible due to the new rule:

         %.c : %.rsc
            rsh -fls -c $< $@

      which says, "in order to turn a .rsc file into a .c file, run the
      following rsh command."  Thus, when make considers test.o, it uses
      its builtin rule for making .o files from .c files, and it then looks
      for `test.c'.  Since it doesn't find test.c, it next determines if
      it has a rule for making .c files.  Discovering it can make a .c file
      from a .rsc file, and further finding a .rsc file with the same basename
      as the object it is trying to make, it applies the rule and runs rsh.
      So, the first step in making test.o is:

         rsh -fls -c test.rsc test.c

      which creates test.c based upon the resource file `test.rsc' and
      the default skeleton file `c_rsh.skl' (located along the LIB path).
      The data objects in test.c are made static and far, and the type of
      `ob_spec' is taken to be "unsigned long".  After creating test.c,
      make then applies the rule for making a .o file from a .c file and
      runs this command:

         lc -rr -v -w -cfuis -d1 test.c

      which creates the desired target test.o.  Finally, after running the
      command to link the final program, make deletes the temporary file
      created during the make process, namely, test.c (although test.c is
      no longer needed, you can of course use make's .PRECIOUS pseudo-target
      to suppress the deletion).


      The supplied c_rsh.skl file
      ---------------------------

      You should find one skeleton file, c_rsh.skl, among the files making
      up the RSC-Tools package.  This file is designed for Lattice C 5, but
      it shouldn't be too difficult to modify it for other compilers.  This
      file contains all the support code that is required to imbed a resource
      file within a program; the replacement functions use exactly the same
      syntax as the standard GEM functions, so one may easily compile with
      or without use of rsh, in other words, switch between using a standard,
      non-imbedded resource and an imbedded one.  Please see the skeleton
      file for additional comments.  In particular, Lattice C 5 #defines
      several AES functions, including some we're replacing, so you will need
      to be aware of this!


OPTIONS SUMMARY

      Rsh support flexible ordering of options, as well as option
      concatenation.  For example, the following commands:

         rsh -b -f -l test.rsc test.rsh
         rsh -bfl test.rsc test.rsh
         rsh test.rsc -bf test.rsh -l

      are equivalent.  Rsh interprets any `-' character as introducing an
      option.  If one happens to have a file beginning with `-', the "end
      of the options" can be indicated with the special token "--" (two
      dashes).  Everything following the double-dash is assumed to be a
      non-option.  Finally, consider the `-c' option again.  It was earlier
      said to optionally take an argument, the name of a skeleton file.
      While an option requiring an argument may be separated from its
      argument by whitespace, options that optionally take an argument
      must be immediately followed by their arguments.  Thus, the following:

         rsh -c a.skl test.rsc test.c

      won't work, because rsh doesn't recognize `a.skl' as the argument
      to `-c'.  Rather, it assumes a.skl is the resource file, and searches
      for the default skeleton file in the LIB path(s).  The correct
      usage is:

         rsh -ca.skl test.rsc test.c

      which loads the a.skl skeleton file, as desired.

      The rsh options are summarized below.

      -b                   Escape backslashes in quoted strings.

      -ac [skeleton file]  Incorporate RSH output into a skeleton file.
                           The filename argument is optional, and if
                           given, must immediately follow the option
                           character.  (Note: the `-a' option currently
                           duplicates the functionality of `-c'; at some
                           later date it may support assembly output)

      -f                   Make data objects far.

      -l                   Use "unsigned long" as the type of `ob_spec'
                           (the default is "void *").

      -n                   Make data objects near.

      -q                   Escape quotes within quoted strings.

      -s                   Make data objects static.

      -t                   Pad TEDINFO `te_ptext' fields with '\0' so they
                           are at least as long as their corresponding
                           `te_pvalid' fields (for compatibility with the
                           Kuma/MWC editor).

      -v                   Verbose mode.

      -V                   Print version and copyright notice.

NOTES

      Like most programming tools, rsh assumes you know what you're doing.
      In particular, you won't be warned before rsh overwrites a file.
      When generating a C file from a resource file, be careful that the
      C filename doesn't conflict with any other modules.  One strategy
      to avoid name conflicts is to have specific directories for each
      project, and if, for example, the program is to be named test.prg, do
      not name any module test.c (the module containing the `main' function
      should be called "main.c").  Then one can name the resource file
      "test.rsc" and use rsh in a makefile as described above; rsh will
      create test.c as needed, make will delete it after it's compiled
      successfully, and as long as these conventions are followed, there
      will be no danger of inadvertently overwriting any files.

AUTHOR

      Doug Harrison

      Electronic mail:

         GEnie: D.S.HARRISON
         Bix: dharrison
         Compuserve: 72277,2315

      U.S. Mail:

         Doug Harrison
         P.O. Box 66236
         Baton Rouge, LA 70806-6236

      Please send any comments and criticisms to any of the above
      addresses.  Shareware donations cheerfully accepted! (see the
      accompanying README.TXT file for details on this and distribution
      instructions)